远程 GUI - waypipe

要点：用 WSLg + waypipe + ssh，Docker 容器里的 SDL3 程序就能把窗口显示到 Windows 桌面，Windows 侧不用装 X server。容器没有 GPU，由 Mesa llvmpipe 做软件渲染，适合调试界面，不适合做性能评估。

验证环境（2026-09）：容器是 Ubuntu 26.04 + s6-overlay，sshd 端口 1022；客户端是 WSL 2.7.3 + Ubuntu 26.04（开启 systemd），两端均为 waypipe 0.11；程序是 PixSee，由 vcpkg 静态链接 SDL3。

PixSee ─Wayland─▶ waypipe server ═ssh═▶ waypipe client ─▶ WSLg ─▶ Windows 桌面

waypipe 在两端都要在 $XDG_RUNTIME_DIR 下创建或连接 socket，所以两端都要有这个变量。
静态链接的 SDL3 在运行时 dlopen 加载 Wayland、EGL 等库，所以 ldd 里看不到它们，缺库时只会在运行时报错。
只要 WAYLAND_DISPLAY 有效，SDL3 会自动选 Wayland，不需要设置 SDL_VIDEODRIVER。

容器端

# 这些 -dev 包是 SDL3 Wayland 后端的构建依赖，依赖链会顺带装上 libwayland-client0、libegl-mesa0、libgl1 等运行时库
sudo apt install --no-install-recommends waypipe \
  libwayland-dev libxkbcommon-dev wayland-protocols libegl-dev libdecor-0-dev
# 容器里没有 logind，要手动建目录；sshd 开了 UsePAM，pam_env 会把 /etc/environment 注入 ssh 会话
sudo install -d -m 700 -o 1000 -g 100 /run/user/1000
echo 'XDG_RUNTIME_DIR="/run/user/1000"' | sudo tee -a /etc/environment

以上配置已写进镜像源 Dockyard/ubuntu2604-user.dockerfile。目录在镜像构建时创建，之所以能保留下来，是因为 s6-overlay 平时不会往 /run 上挂 tmpfs（见 libexec/preinit）。如果开启了 S6_READ_ONLY_ROOT，或者启动时加了 --tmpfs /run，就要改用 s6 oneshot 服务，在启动时创建这个目录。

WSL 端

sudo apt install waypipe
ls -l $XDG_RUNTIME_DIR/wayland-0   # 应该是指向 /mnt/wslg/runtime-dir/wayland-0 的软链接

开启 systemd 后，$XDG_RUNTIME_DIR 由 logind 接管，里面可能没有 wayland-0。较新的 WSL 会用 wslg-session.service 自动创建这个链接（用 systemctl --user cat 查看）；旧版本要自己执行 ln -sf /mnt/wslg/runtime-dir/wayland-0 $XDG_RUNTIME_DIR/。

使用

waypipe --no-gpu ssh -p 1022 amass@192.168.110.4 /home/amass/Projects/PixSee/build/ubuntu-debug/PixSee

想确认程序确实走了 Wayland 和 llvmpipe，可以在容器里执行 grep -oE 'libwayland-client|libgallium' /proc/$(pgrep -x PixSee)/maps | sort -u。

常见问题

现象	原因与处理
ssh 把 `host:/path` 整串当主机名	`host:path` 是 scp 的写法，ssh 的主机和命令之间要用空格分开
`XDG_RUNTIME_DIR not present`	远端没有这个变量或目录，按容器端配置补上；临时绕过可以加 `--display /tmp/wayland-waypipe`
`No available video device`	SDL 没能 dlopen 到 Wayland 库，或者没通过 waypipe 启动程序
`Failed to initialize OpenGL context`	RmlUi 的 glad 要 dlopen `libGL.so.1`，缺 `libgl1`。同时出现的 ZINK、dri2 报错只是 Mesa 探测硬件驱动失败的日志
`No plugins found, falling back on no decorations`	libdecor 没有装插件，所以没有标题栏；自绘窗口框的程序不受影响

延伸：man waypipe（--no-gpu、--compress、--display）、SDL3 的 SDL_HINT_VIDEO_DRIVER、Mesa 的 LIBGL_ALWAYS_SOFTWARE。

远程 GUI - waypipe